Skip to main content

Getting Started

To run any Terraform or Ansible commands against the fleet, set up the following first.

1. Proxmox API token​

Terraform authenticates to Proxmox with an API token. Export the secret half before running anything:

export TF_VAR_pm_api_token_secret="your_token_secret_here"

2. Bitwarden CLI​

Most make targets pull secrets (GitHub PATs, the Cloudflare token, Hugging Face tokens, registry/admin passwords, API keys) from Bitwarden at runtime via the bw CLI, rather than storing them in the repo. Install bw and make sure you're logged in and unlocked before running those targets.

3. SSH configuration (ProxyJump)​

The Proxmox VMs live on a private network (10.0.0.0/24, gateway 10.0.0.254) and aren't directly reachable. Configure ~/.ssh/config to jump through the public-facing Proxmox host — the host aliases below match the Ansible inventory, so Ansible reuses your ProxyJump and keys automatically:

Host docker-build synthesis-test-vm webserver-vm observability-vm api-gateway-vm services-user-vm services-staff-vm
    User ansible-control
    ProxyJump <your-proxmox-jump-host>

Host docker-build
    HostName 10.0.0.12
Host synthesis-test-vm
    HostName 10.0.0.13
Host webserver-vm
    HostName 10.0.0.14
Host observability-vm
    HostName 10.0.0.15
Host api-gateway-vm
    HostName 10.0.0.17
Host services-user-vm
    HostName 10.0.0.18
Host services-staff-vm
    HostName 10.0.0.19

Two hosts sit outside this pattern, since they aren't Proxmox VMs:

  • Amergin (the GPU server) is reached directly over SSH — it isn't behind the Proxmox jump host.
  • Puca (the Raspberry Pi) is managed from a separate control node, setanta, which reaches it directly by SSH (no ProxyJump).

4. Local tooling​

Install terraform, ansible, and make on your workstation.

Once these are in place, see Common Operations for the full list of make targets, or Modifying Infrastructure to make a specific kind of change.